home *** CD-ROM | disk | FTP | other *** search
/ Network PC / Network PC.iso / installations / amiga emulator / _setup.1 / README.UNIX < prev    next >
Encoding:
Text File  |  1997-06-05  |  11.0 KB  |  236 lines
  1. This file documents the details relevant to the Unix versions of UAE. General
  2. information can be found in the file "README"
  3.  
  4. System requirements
  5. ===================
  6.  
  7. UAE will run on most Unix systems, and by now most of the portability issues
  8. have been sorted out. However, since I am developing UAE using Linux, you may
  9. encounter problems from time to time. If this happens, let me know as soon as
  10. possible so these can be fixed in the next release.
  11.  
  12. These are the requirements for getting the Unix version to run:
  13.   - X11, or SVGAlib if you are using Linux.
  14.   - The 386 is the only CPU that UAE will not run on. You need a 486 or
  15.     higher if you want to use an Intel CPU.
  16.   - an ANSI C compiler. Do not use a K&R compiler, otherwise you risk getting
  17.     incorrect code. GCC is _strongly_ recommended.
  18.   - 8MB RAM (better 16MB) + some swap
  19.   - Optionally, tcl7.4/tk4.0 or the X Forms library (version 0.80 or higher)
  20.  
  21.  
  22. Compilation
  23. ===========
  24.  
  25. To build UAE, first unpack it to an appropriate directory (e.g. /usr/src/uae
  26. on a Linux system). The simple way to proceed is to type "configure; make", 
  27. after that has completed you should have a working X11 version of UAE. Ignore
  28. warnings if you get them.
  29.  
  30. However, you should probably have a look at some of the compile-time options
  31. found in "config.h" before you do this. There are some things you can change
  32. there so that the resulting executable will perform better on your machine.
  33. Each of the options in that file has a description. You can edit config.h to
  34. suit your needs; and then do "configure; make" afterwards.
  35.  
  36. When running configure, there are a few options that you can use to
  37. influence configure's decision as to what kind of display should be used.
  38. The following displays are available:
  39.   - Standard X11, in a window. This is the default
  40.   - X11/DGA. This runs full-screen and is somewhat faster than the normal X11
  41.     code. You need a recent (>= version 3.2) XFree86 X server.
  42.   - SVGAlib. This is only available on Linux systems. It is the default if X11
  43.     is not found by configure.
  44.   - ncurses character output. This is the last resort.
  45.  
  46. Type "configure --help" to get a list of options that configure understands.
  47. The following are likely to be useful:
  48.   --without-x        : Don't use X11 as target.
  49.   --with-svgalib     : Build a version that uses SVGAlib (Linux only)
  50.   --with-ggi         : Build a version that uses GGI (Linux only)
  51.   --with-asciiart    : Build a version that uses ASCII "graphics"
  52.   --enable-profiling : Build a much slower version of the emulator (if you 
  53.                        don't know what it's for, you don't want it)
  54.   --enable-dga       : If your X server supports the DGA extension, use it
  55.   --enable-ui        : Build a user interface if possible (enabled by default)
  56.   --enable-xfgui     : For the X11 version, enable an alternate GUI using the
  57.                        X Forms library. The standard X GUI requires Tcl/Tk
  58.                        7.4/4.0.
  59.   --enable-threads   : Build UAE multithreaded on systems that support it.
  60.                        Note that there is very little thread support in UAE at
  61.                the moment.
  62.   --enable-penguins  : Enable some additional threads which only make sense on
  63.                        SMP (symmetric multi penguin) machines. If you have a
  64.                single-CPU machine, you don't want to use this option.
  65. Note that there is a corresponding "--disable-xxx" for each "--enable-xxx"
  66. option, and a "--without-yyy" for each "--with-yyy".
  67.  
  68. Both the SVGAlib and the DGA version run full-screen, i.e. you can't run other
  69. programs at the same time very well. You also need to be root to run either of
  70. these two versions.
  71. Making UAE suid root is _not_ a particularly good idea if you care about the
  72. security of your system.
  73.  
  74. If you don't give any options affecting the GUI, configure will try to set up
  75. UAE to use the Tcl/Tk GUI. It needs to find the program "wish4.0" in the path
  76. to be able to do that.
  77.  
  78. If you are not sure whether you have an SMP machine, you don't have one.
  79.  
  80.  
  81. Run-time options
  82. ================
  83.  
  84. The X11 version (without DGA) of UAE understands these special command-line
  85. options:
  86.   -L     : Use "low-bandwidth" mode, which can reduce the amount of data
  87.            transferred between UAE and the X server. That's particularly an
  88.        advantage when these are running on two different machines in a
  89.        network.
  90.   -T     : Use the MIT-SHM extension. This may not be available on all
  91.            machines, and it will not work if UAE and the X server are not
  92.        running on the same machine.
  93.        In all other configurations, turning on this option will give you
  94.        a huge speed improvement.
  95.   -x     : Turn off the X11 mouse cursor for the UAE window. Personally, I
  96.            find that seeing the X cursor helps, but that's a matter of taste.
  97.  
  98. The SVGAlib version understands the following command-line option:
  99.   -x     : Turn off linear frame buffer support, even if it is available.
  100.            Unless linear mode doesn't work properly, you don't want to disable
  101.        it, because UAE is much faster if it can draw into a linear
  102.        frame buffer.
  103.  
  104.  
  105. Keyboard mappings
  106. =================
  107.  
  108. You can exit the SVGAlib (and the DGA) version by pressing the F12 key.
  109. PgUp/PgDn emulate the right/left Amiga keys. In the SVGAlib version, F11 will
  110. bring you back to the user interface screen so you can change disks during the
  111. emulation.
  112.  
  113. The X11 version needs some help to figure out how to map keys: You'll have to
  114. tell it the keyboard language with the "-l" commandline option. Several
  115. languages ("us", "se", "de", "fr", "es", "it") are supported. If you have
  116. a different keyboard, patches to make UAE work with it are appreciated.
  117.  
  118.  
  119. Mouse and joystick emulation
  120. ============================
  121.  
  122. The X11 (non-DGA) version has one problem: There are two mouse pointers, the
  123. X mouse pointer and the Y mouse pointer. You can work that way, but you get
  124. confused quickly.
  125. The solution in previous (0.6.8 and before) versions of UAE was a small piece
  126. of code that looked at the position of sprite 0 on the screen and tried to
  127. generate mouse movements in an emulated hardware port. That worked reasonably
  128. well, but had several problems.
  129. The new solution is to use a small Amiga program which is called "mousehack".
  130. You will find this in the "amiga" subdirectory. Put it into the directory that
  131. you use for harddisk emulation so that you can run it from the emulator. Then
  132. put the command "run >NIL: mousehack" at the top of your startup-sequence. UAE
  133. will detect when this program is running and use the improved mouse pointer
  134. positioning method. (Don't run this program on old versions of UAE)
  135. If the program is not running, you get the old behaviour - almost. By default,
  136. the emulator will no longer try to keep Amiga and X mouse pointers at the same
  137. position, because that led to problems in the past. You can toggle this
  138. behaviour with F12.
  139. (If you just added "run mousehack" to your startup-sequence, that would have
  140. the effect that the initial CLI window would be impossible to close.
  141. Unfortunately, redirecting output to >NIL: disables all error messages that
  142. mousehack can give you - so if it does not work, try running it by hand
  143. without the >NIL: redirection.)
  144.  
  145. If you find a program in which the mouse pointer does not move at all if you
  146. use the X11 version, start that program with mousehack _not_ running
  147. (Magnetic Scrolls adventures are known to need this, for example).
  148.  
  149. The SVGAlib and DGA versions are not affected by any of this (and pressing F12
  150. exits those versions).
  151.  
  152. If you use Linux and have the joystick driver kernel module, "configure"
  153. should automatically enable support for it. UAE calibrates the joystick
  154. automatically. Turn it a few times on startup to get the calibration done. 
  155.  
  156.  
  157. Harddisk emulation
  158. ==================
  159.  
  160. Please read the appropriate sections in the file "README" on how to use the
  161. filesystem emulation. There are a few Unix-specific things about it, though.
  162.  
  163. If you want to execute files located on a native filesystem, they need to have
  164. the x permission bit set. That can be done in Unix by "chmod +x file" or in
  165. AmigaDOS with "protect file rwed".
  166. You should set aside a whole directory tree for AmigaOS files, and not use it
  167. from Unix in any way if you can avoid it. Changing permissions/owners,
  168. creating symbolic links and doing other stuff that AmigaOS does not know about
  169. is a good way to confuse the emulator and the emulated software. E.g. it's
  170. possible to have a symlink pointing at a mounted CD-ROM. The emulator would
  171. see that as a directory inside which it gets "read only filesystem" errors,
  172. and wouldn't know what to do about it. Avoid this sort of thing. It's best to
  173. start with an empty harddisk emulation directory and install software there
  174. only from within the emulation.
  175. The following setup can also lead to problems:
  176.   -m dh0:/foo -m dh1:/foo/bar
  177. Please take care that the filesystems you mount don't overlap each other
  178. (another great reason not to use symbolic links within them).
  179.  
  180.  
  181. Printing
  182. ========
  183.  
  184. If you give UAE the "-p lpr" option, output for the parallel port will be
  185. piped to lpr, which will in turn print it. You should use the Postscript
  186. printer driver on the Amiga side (since UAE relies on the ^D character at
  187. the end of the Postscript output).
  188. Note that I never tried this myself, so you're on your own.
  189.  
  190.  
  191. Transferring things over the serial port
  192. ========================================
  193.  
  194. There's an easy way to use a null-modem cable without terminal software if
  195. you use Linux (and probably other Unices). You can do
  196.  
  197.   transdisk >SER: <options>
  198.  
  199. on the Amiga to copy the data directly to the serial port. Before that, do
  200.  
  201.   cat /dev/ttyS1 >df0.adf
  202.   
  203. on your Linux box to receive the data (it may be ttyS0 on your system, or
  204. another number, depending on which serial port you are using). When the Amiga
  205. is done transferring, hit ^C on the PC to interrupt the cat program. To make
  206. this work, you need to use the same settings for the serial port on both
  207. sides. This is done with the Preferences program on the Amiga (this is split
  208. into several programs from Kickstart 2.0 upwards, you'll find a program called
  209. "serial" in the Prefs directory of your Workbench disk). On the Linux side,
  210. use the stty program. "man stty" will give you the manpage describing how to
  211. use it.
  212. To be on the safe side, set the speed to a low value (2400 baud). Turn off
  213. Xon/Xoff, but enable RTS/CTS.
  214. I use the following command myself:
  215.  
  216.   stty 19200 parenb -cstopb cread clocal crtscts -istrip -inlcr -icrnl -opost
  217.     -onlcr -parodd -isig -icanon -iexten raw cs8 </dev/ttyS1
  218.  
  219. which is probably overkill, but you never know :)
  220. This maps to 19200 baud, 8 bits, even parity, one stop bit, which you have to
  221. set in the Amiga preferences.
  222.  
  223.  
  224. Using the Linux AFFS filesystem
  225. ===============================
  226.  
  227. If you use Linux with a kernel version >= 2.0.7 and version 2.5k of the mount
  228. program, you can do
  229.    mount df0.adf /mnt -t affs -o loop
  230. to mount disk image df0.adf at the mount point /mnt. This is much more
  231. convenient than using the "readdisk" program.
  232.  
  233. You'll need to enable support for the Amiga filesystem and the loop device
  234. when configuring and compiling the kernel (say yes to the "Ask about
  235. experimental drivers" question at the start).
  236.